3 * Defines an interface for messages with additional machine-readable data for
4 * use by the API, and provides concrete implementations of that interface.
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License along
17 * with this program; if not, write to the Free Software Foundation, Inc.,
18 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 * http://www.gnu.org/copyleft/gpl.html
25 * Interface for messages with machine-readable data for use by the API
29 interface IApiMessage
extends MessageSpecifier
{
31 * Returns a machine-readable code for use by the API
33 * The message key is often sufficient, but sometimes there are multiple
34 * messages used for what is really the same underlying condition (e.g.
35 * badaccess-groups and badaccess-group0)
38 public function getApiCode();
41 * Returns additional machine-readable data about the error condition
44 public function getApiData();
47 * Sets the machine-readable code for use by the API
48 * @param string|null $code If null, the message key should be returned by self::getApiCode()
49 * @param array|null $data If non-null, passed to self::setApiData()
51 public function setApiCode( $code, array $data = null );
54 * Sets additional machine-readable data about the error condition
57 public function setApiData( array $data );
61 * Extension of Message implementing IApiMessage
64 * @todo: Would be nice to use a Trait here to avoid code duplication
66 class ApiMessage
extends Message
implements IApiMessage
{
67 protected $apiCode = null;
68 protected $apiData = array();
71 * Create an IApiMessage for the message
73 * This returns $msg if it's an IApiMessage, calls 'new ApiRawMessage' if
74 * $msg is a RawMessage, or calls 'new ApiMessage' in all other cases.
76 * @param Message|RawMessage|array|string $msg
77 * @param string|null $code
78 * @param array|null $data
81 public static function create( $msg, $code = null, array $data = null ) {
82 if ( $msg instanceof IApiMessage
) {
84 } elseif ( $msg instanceof RawMessage
) {
85 return new ApiRawMessage( $msg, $code, $data );
87 return new ApiMessage( $msg, $code, $data );
92 * @param Message|string|array $msg
93 * - Message: is cloned
94 * - array: first element is $key, rest are $params to Message::__construct
95 * - string: passed to Message::__construct
96 * @param string|null $code
97 * @param array|null $data
100 public function __construct( $msg, $code = null, array $data = null ) {
101 if ( $msg instanceof Message
) {
102 foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
103 if ( isset( $msg->$key ) ) {
104 $this->$key = $msg->$key;
107 } elseif ( is_array( $msg ) ) {
108 $key = array_shift( $msg );
109 parent
::__construct( $key, $msg );
111 parent
::__construct( $msg );
113 $this->apiCode
= $code;
114 $this->apiData
= (array)$data;
117 public function getApiCode() {
118 return $this->apiCode
=== null ?
$this->getKey() : $this->apiCode
;
121 public function setApiCode( $code, array $data = null ) {
122 $this->apiCode
= $code;
123 if ( $data !== null ) {
124 $this->setApiData( $data );
128 public function getApiData() {
129 return $this->apiData
;
132 public function setApiData( array $data ) {
133 $this->apiData
= $data;
136 public function serialize() {
137 return serialize( array(
138 'parent' => parent
::serialize(),
139 'apiCode' => $this->apiCode
,
140 'apiData' => $this->apiData
,
144 public function unserialize( $serialized ) {
145 $data = unserialize( $serialized );
146 parent
::unserialize( $data['parent'] );
147 $this->apiCode
= $data['apiCode'];
148 $this->apiData
= $data['apiData'];
153 * Extension of RawMessage implementing IApiMessage
156 * @todo: Would be nice to use a Trait here to avoid code duplication
158 class ApiRawMessage
extends RawMessage
implements IApiMessage
{
159 protected $apiCode = null;
160 protected $apiData = array();
163 * @param RawMessage|string|array $msg
164 * - RawMessage: is cloned
165 * - array: first element is $key, rest are $params to RawMessage::__construct
166 * - string: passed to RawMessage::__construct
167 * @param string|null $code
168 * @param array|null $data
171 public function __construct( $msg, $code = null, array $data = null ) {
172 if ( $msg instanceof RawMessage
) {
173 foreach ( get_class_vars( get_class( $this ) ) as $key => $value ) {
174 if ( isset( $msg->$key ) ) {
175 $this->$key = $msg->$key;
178 } elseif ( is_array( $msg ) ) {
179 $key = array_shift( $msg );
180 parent
::__construct( $key, $msg );
182 parent
::__construct( $msg );
184 $this->apiCode
= $code;
185 $this->apiData
= (array)$data;
188 public function getApiCode() {
189 return $this->apiCode
=== null ?
$this->getKey() : $this->apiCode
;
192 public function setApiCode( $code, array $data = null ) {
193 $this->apiCode
= $code;
194 if ( $data !== null ) {
195 $this->setApiData( $data );
199 public function getApiData() {
200 return $this->apiData
;
203 public function setApiData( array $data ) {
204 $this->apiData
= $data;
207 public function serialize() {
208 return serialize( array(
209 'parent' => parent
::serialize(),
210 'apiCode' => $this->apiCode
,
211 'apiData' => $this->apiData
,
215 public function unserialize( $serialized ) {
216 $data = unserialize( $serialized );
217 parent
::unserialize( $data['parent'] );
218 $this->apiCode
= $data['apiCode'];
219 $this->apiData
= $data['apiData'];